home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / catn / pack.n < prev    next >
Text File  |  1994-09-20  |  13KB  |  331 lines
  1.  
  2.  
  3.  
  4. pack(n)                    Tk Commands
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      pack - Geometry manager that packs around edges of cavity
  12.  
  13. SYNOPSIS
  14.      pack _o_p_t_i_o_n _a_r_g ?_a_r_g ...?
  15. _________________________________________________________________
  16.  
  17.  
  18. DESCRIPTION
  19.      The pack command is used to communicate with the  packer,  a
  20.      geometry  manager  that arranges the children of a parent by
  21.      packing them in order around the edges of the  parent.   The
  22.      pack command can have any of several forms, depending on the
  23.      _o_p_t_i_o_n argument:
  24.  
  25.      pack _s_l_a_v_e ?_s_l_a_v_e ...? ?_o_p_t_i_o_n_s?
  26.           If the first argument to pack is  a  window  name  (any
  27.           value  starting  with  ``.''), then the command is pro-
  28.           cessed in the same way as pack configure.
  29.  
  30.      pack configure _s_l_a_v_e ?_s_l_a_v_e ...? ?_o_p_t_i_o_n_s?
  31.           The arguments consist of the names of one or more slave
  32.           windows followed by pairs of arguments that specify how
  33.           to manage the slaves.   See  ``THE  PACKER  ALGORITHM''
  34.           below  for  details  on how the options are used by the
  35.           packer.  The following options are supported:
  36.  
  37.           -after _o_t_h_e_r
  38.                _O_t_h_e_r must the name of another  window.   Use  its
  39.                master  as  the  master for the slaves, and insert
  40.                the slaves just after _o_t_h_e_r in the packing order.
  41.  
  42.           -anchor _a_n_c_h_o_r
  43.                _A_n_c_h_o_r must be a valid anchor position such  as  n
  44.                or  sw;  it specifies where to position each slave
  45.                in its parcel.  Defaults to center.
  46.  
  47.           -before _o_t_h_e_r
  48.                _O_t_h_e_r must the name of another  window.   Use  its
  49.                master  as  the  master for the slaves, and insert
  50.                the slaves just before _o_t_h_e_r in the packing order.
  51.  
  52.           -expand _b_o_o_l_e_a_n
  53.                Specifies whether the slaves should be expanded to
  54.                consume  extra space in their master.  _B_o_o_l_e_a_n may
  55.                have any proper boolean value, such as  1  or  no.
  56.                Defaults to 0.
  57.  
  58.           -fill _s_t_y_l_e
  59.                If a slave's parcel is larger than  its  requested
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. pack(n)                    Tk Commands
  71.  
  72.  
  73.  
  74.                dimensions, this option may be used to stretch the
  75.                slave.  _S_t_y_l_e  must  have  one  of  the  following
  76.                values:
  77.  
  78.                none Give the slave its requested dimensions  plus
  79.                     any internal padding requested with -ipadx or
  80.                     -ipady.  This is the default.
  81.  
  82.                x    Stretch the slave horizontally  to  fill  the
  83.                     entire  width  of  its  parcel  (except leave
  84.                     external padding as specified by -padx).
  85.  
  86.                y    Stretch the  slave  vertically  to  fill  the
  87.                     entire  height  of  its  parcel (except leave
  88.                     external padding as specified by -pady).
  89.  
  90.                both Stretch the slave both horizontally and vert-
  91.                     ically.
  92.  
  93.           -in _o_t_h_e_r
  94.                Insert the slave(s) at  the  end  of  the  packing
  95.                order for the master window given by _o_t_h_e_r.
  96.  
  97.           -ipadx _a_m_o_u_n_t
  98.                _A_m_o_u_n_t specifies how much horizontal internal pad-
  99.                ding  to  leave  on  each  side  of  the slave(s).
  100.                _A_m_o_u_n_t must be a valid screen distance, such as  2
  101.                or .5c.  It defaults to 0.
  102.  
  103.           -ipady _a_m_o_u_n_t
  104.                _A_m_o_u_n_t specifies how much vertical  internal  pad-
  105.                ding  to  leave  on  each  side  of  the slave(s).
  106.                _A_m_o_u_n_t  defaults to 0.
  107.  
  108.           -padx _a_m_o_u_n_t
  109.                _A_m_o_u_n_t specifies how much horizontal external pad-
  110.                ding  to  leave  on  each  side  of  the slave(s).
  111.                _A_m_o_u_n_t defaults to 0.
  112.  
  113.           -pady _a_m_o_u_n_t
  114.                _A_m_o_u_n_t specifies how much vertical  external  pad-
  115.                ding  to  leave  on  each  side  of  the slave(s).
  116.                _A_m_o_u_n_t defaults to 0.
  117.  
  118.           -side _s_i_d_e
  119.                Specifies which side of the  master  the  slave(s)
  120.                will be packed against.  Must be left, right, top,
  121.                or bottom.  Defaults to top.
  122.  
  123.           If no -in, -after or -before option is  specified  then
  124.           each  of  the slaves will be inserted at the end of the
  125.           packing list  for  its  parent  unless  it  is  already
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. pack(n)                    Tk Commands
  137.  
  138.  
  139.  
  140.           managed  by  the  packer (in which case it will be left
  141.           where it is).  If one of  these  options  is  specified
  142.           then  all  the slaves will be inserted at the specified
  143.           point.  If any of the slaves are already managed by the
  144.           geometry  manager then any unspecified options for them
  145.           retain their  previous  values  rather  than  receiving
  146.           default values.
  147.  
  148.      pack forget _s_l_a_v_e ?_s_l_a_v_e ...?
  149.           Removes each of the _s_l_a_v_es from the packing  order  for
  150.           its  master  and unmaps their windows.  The slaves will
  151.           no longer be managed by the packer.
  152.  
  153.      pack newinfo _s_l_a_v_e
  154.           Returns a list whose elements are  the  current  confi-
  155.           guration  state of the slave given by _s_l_a_v_e in the same
  156.           option-value form that might be specified to pack  con-
  157.           figure.   The  first two elements of the list are ``-in
  158.           _m_a_s_t_e_r'' where _m_a_s_t_e_r is the slave's master.   Starting
  159.           with Tk 4.0 this option will be renamed "pack info".
  160.  
  161.      pack propagate _m_a_s_t_e_r ?_b_o_o_l_e_a_n?
  162.           If _b_o_o_l_e_a_n has a true boolean value such  as  1  or  on
  163.           then propagation is enabled for _m_a_s_t_e_r, which must be a
  164.           window name (see ``GEOMETRY PROPAGATION''  below).   If
  165.           _b_o_o_l_e_a_n  has  a false boolean value then propagation is
  166.           disabled for _m_a_s_t_e_r.  In either of these cases an empty
  167.           string  is  returned.   If  _b_o_o_l_e_a_n is omitted then the
  168.           command returns 0 or 1 to indicate whether  propagation
  169.           is   currently  enabled  for  _m_a_s_t_e_r.   Propagation  is
  170.           enabled by default.
  171.  
  172.      pack slaves _m_a_s_t_e_r
  173.           Returns a list of all of  the  slaves  in  the  packing
  174.           order  for _m_a_s_t_e_r.  The order of the slaves in the list
  175.           is the same as their order in the  packing  order.   If
  176.           _m_a_s_t_e_r has no slaves then an empty string is returned.
  177.  
  178.  
  179. THE PACKER ALGORITHM
  180.      For each master the packer  maintains  an  ordered  list  of
  181.      slaves  called  the  _p_a_c_k_i_n_g  _l_i_s_t.   The  -in,  -after, and
  182.      -before configuration options are used to specify the master
  183.      for each slave and the slave's position in the packing list.
  184.      If none of these options is given for a slave then the slave
  185.      is added to the end of the packing list for its parent.
  186.  
  187.      The packer arranges the slaves for a master by scanning  the
  188.      packing list in order.  At the time it processes each slave,
  189.      a rectangular area within the master is  still  unallocated.
  190.      This  area  is called the _c_a_v_i_t_y;  for the first slave it is
  191.      the entire area of the master.
  192.  
  193.  
  194.  
  195. Tk                                                              3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. pack(n)                    Tk Commands
  203.  
  204.  
  205.  
  206.      For each slave the packer carries out the following steps:
  207.  
  208.      [1]  The packer allocates a rectangular _p_a_r_c_e_l for the slave
  209.           along the side of the cavity given by the slave's -side
  210.           option.  If the side is top or bottom then the width of
  211.           the parcel is the width of the cavity and its height is
  212.           the requested height of the slave plus the  -ipady  and
  213.           -pady  options.   For the left or right side the height
  214.           of the parcel is the height of the cavity and the width
  215.           is the requested width of the slave plus the -ipadx and
  216.           -padx options.  The  parcel  may  be  enlarged  further
  217.           because of the -expand option (see ``EXPANSION'' below)
  218.  
  219.      [2]  The packer chooses the dimensions of  the  slave.   The
  220.           width will normally be the slave's requested width plus
  221.           twice its -ipadx option and the height will normally be
  222.           the  slave's  requested  height  plus  twice its -ipady
  223.           option.  However, if the -fill option is x or both then
  224.           the width of the slave is expanded to fill the width of
  225.           the parcel, minus twice the -padx option.  If the -fill
  226.           option  is  y  or  both then the height of the slave is
  227.           expanded to fill the width of the parcel,  minus  twice
  228.           the -pady option.
  229.  
  230.      [3]  The packer positions the slave over its parcel.  If the
  231.           slave  is  smaller  than  the  parcel  then the -anchor
  232.           option determines where in the parcel the slave will be
  233.           placed.   If -padx or -pady is non-zero, then the given
  234.           amount of external padding will always be left  between
  235.           the slave and the edges of the parcel.
  236.  
  237.      Once a given slave has been packed, the area of  its  parcel
  238.      is subtracted from the cavity, leaving a smaller rectangular
  239.      cavity for the next slave.  If a slave doesn't  use  all  of
  240.      its  parcel, the unused space in the parcel will not be used
  241.      by subsequent slaves.  If the cavity should become too small
  242.      to  meet  the  needs of a slave then the slave will be given
  243.      whatever space is left in the cavity.  If the cavity shrinks
  244.      to  zero size, then all remaining slaves on the packing list
  245.      will be unmapped from the screen  until  the  master  window
  246.      becomes large enough to hold them again.
  247.  
  248.  
  249. EXPANSION
  250.      If a master window is so large  that  there  will  be  extra
  251.      space  left  over  after all of its slaves have been packed,
  252.      then the extra space is distributed uniformly among  all  of
  253.      the  slaves for which the -expand option is set.  Extra hor-
  254.      izontal space is distributed  among  the  expandable  slaves
  255.      whose  -side  is  left or right, and extra vertical space is
  256.      distributed among the expandable slaves whose -side  is  top
  257.      or bottom.
  258.  
  259.  
  260.  
  261. Tk                                                              4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. pack(n)                    Tk Commands
  269.  
  270.  
  271.  
  272. GEOMETRY PROPAGATION
  273.      The packer normally computes how large a master must  be  to
  274.      just  exactly  meet the needs of its slaves, and it sets the
  275.      requested width and height of the  master  to  these  dimen-
  276.      sions.   This  causes  geometry  information to propagate up
  277.      through a window hierarchy to a top-level window so that the
  278.      entire  sub-tree  sizes  itself to fit the needs of the leaf
  279.      windows.  However, the pack propagate command may be used to
  280.      turn  off  propagation for one or more masters.  If propaga-
  281.      tion is disabled then the packer will not set the  requested
  282.      width  and height of the packer.  This may be useful if, for
  283.      example, you wish for a master window to have a  fixed  size
  284.      that you specify.
  285.  
  286.  
  287. RESTRICTIONS ON MASTER WINDOWS
  288.      The master for each slave must either be the slave's  parent
  289.      (the  default)  or a descendant of the slave's parent.  This
  290.      restriction is necessary to guarantee that the slave can  be
  291.      placed  over  any part of its master that is visible without
  292.      danger of the slave being clipped by its parent.
  293.  
  294.  
  295. PACKING ORDER
  296.      If the master for a slave is not its parent  then  you  must
  297.      make  sure  that  the  slave is higher in the stacking order
  298.      than the master.  Otherwise  the  master  will  obscure  the
  299.      slave  and it will appear as if the slave hasn't been packed
  300.      correctly.  The easiest way to make sure the slave is higher
  301.      than  the  master is to create the master window first:  the
  302.      most recently created window will be highest in the stacking
  303.      order.   Or,  you  can  use  the raise and lower commands to
  304.      change the stacking order of either the master or the slave.
  305.  
  306.  
  307. KEYWORDS
  308.      geometry manager,  location,  packer,  parcel,  propagation,
  309.      size
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327. Tk                                                              5
  328.  
  329.  
  330.  
  331.